#%RAML 0.8
title: Permissions
version: v1
baseUri: http://github.com/org/folio/mod-auth/permissions

documentation:
  - title: mod-auth permissions API
    content: This module is responsible for managing and retrieving permissions in the FOLIO system

schemas:
  - permission: !include schemas/permission.json
  - permission-patch: !include schemas/permission.json
  - permissionNameObject: !include schemas/permissionNameObject.json
  - permissionListObject: !include schemas/permissionListObject.json
  - permissionUser: !include schemas/permissionUser.json
  - permissionUserListObject: !include schemas/permissionUserListObject.json
  - permissionNameListObject: !include schemas/permissionNameListObject.json
  - errors: !include ../../raml-util/schemas/errors.schema
  - error: !include ../../raml-util/schemas/error.schema
  - parameters: !include ../../raml-util/schemas/parameters.schema

traits:
  - validate: !include ../../raml-util/traits/validation.raml
  - pageable:
      queryParameters:
        length:
          description: "The maximum number of results to return."
          required: false
          type: integer
          example: 10
          minimum: 1
          default: 10
          maximum: 1000
        start:
          description: "The starting index in a list of results (starts at one)."
          required: false
          type: integer
          minimum: 1
          default: 1
          maximum: 1000
  - sortable:
      queryParameters:
        sortBy:
          description: "A comma-separated list of fieldnames to sort by"
          required: false
          type: string
  - queryable:
      queryParameters:
        query:
          description: "A query string to filter users based on matching criteria in fields."
          required: false
          type: string
  - byPermission:
      queryParameters:
        hasPermissions:
          description: "A list of permissions that any returned users must possess."
          required: false
          type: string
  - byMember:
      queryParameters:
        memberOf:
          description: "A list of permission names that any returned permission must be a sub-permission of."
          required: false
          type: string
  - byOwner:
      queryParameters:
        ownedBy:
          description: "A list of user names that any returned permissions must belong to."
          required: false
          type: string

/perms:
  /users:
    get:
      description: Get a list of users
      is: [
        pageable,
        sortable,
        queryable,
        byPermission
      ]
      responses:
        200:
          body:
            application/json:
              schema: permissionUserListObject
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        403:
          description: "Access Denied"
          body:
            text/plain:
              example: "Access Denied"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    post:
      description: Add a new user
      is: [validate]
      body:
        application/json:
          schema: permissionUser
      responses:
        201:
          body:
            application/json:
              schema: permissionUser
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    /{username}:
      get:
        description: Get a permission user
        responses:
          200:
            body:
              application/json:
                schema: permissionUser
          403:
            description: "Access Denied"
            body:
              text/plain:
                example: "Access Denied"
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User does not exist"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      put:
        description: Modify an existing user
        body:
          application/json:
            schema: permissionUser
        responses:
          200:
            body:
              application/json:
                schema: permissionUser
          400:
            description: "Bad request"
            body:
              text/plain:
                example: "Bad request"
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      delete:
        description: Remove a user
        responses:
          204:
            body:
              text/plain: !!null
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      /permissions:
        get:
          description: Get permissions that a user has
          queryParameters:
            expanded:
              description: Recursively return all subpermissions
              required: false
              type: string
              example: "true"
            full:
              description: Return full permission objects, as opposed to just permission names
              required: false
              type: string
              example: "true"
          responses:
            200:
              description: "An object of returned permissions"
              body:
                application/json:
                  schema: permissionNameListObject
            403:
              description: "Access Denied"
              body:
                text/plain:
                  example: "Access Denied"
            404:
              description: "User not found"
              body:
                text/plain:
                  example: "User not found"
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
        post:
          description: Add a permission to a user
          is: [validate]
          body:
            application/json:
              schema: permissionNameObject
          responses:
            200:
              description: "The added permission"
              body:
                application/json:
                  schema: permissionNameObject
            400:
              description: "Bad request"
              body:
                text/plain:
                  example: "Bad request"
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
        /{permissionname}:
          delete:
            description: Remove a permission from a user
            responses:
              204:
                body:
                  text/plain: !!null
              400:
                description: "Bad request"
                body:
                  text/plain:
              404:
                description: "Permission not found in user"
                body:
                  text/plain:
                    example: "Permission not found in user"
              500:
                description: "Internal server error"
                body:
                  text/plain:
                    example: "Internal server error"
  /permissions:
    get:
      description: Get a list of existing permissions
      queryParameters:
        expandSubs:
          description: Return subpermissions as objects
          required: false
          type: string
          example: "true"
      is: [
        pageable,
        sortable,
        queryable,
        byMember,
        byOwner
      ]
      responses:
        200:
          body:
            application/json:
              schema: permissionListObject
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    post:
      description: Add a new permission
      is: [validate]
      body:
        application/json:
          schema: permission
      responses:
        201:
          body:
            application/json:
              schema:
                permission
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    /{id}:
      get:
        description: Get an existing permission by id
        responses:
          200:
            body:
              application/json:
                schema: permission
          404:
            description: "Permission not found"
            body:
              text/plain:
                example: "Permission not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      put:
        description: Modify an existing permission
        body:
          application/json:
            schema: permission
        responses:
          200:
            body:
              application/json:
                schema: permission
          400:
            description: "Bad request"
            body:
              text/plain:
                example: "Bad request"
          404:
            description: "Permission not found"
            body:
              text/plain:
                example: "Permission not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      delete:
        description: Remove a permission
        responses:
          204:
            body:
              text/plain: !!null
          404:
            description: "Permission not found"
            body:
              text/plain:
                example: "Permission not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"

